package away3d.animators
{
	import away3d.animators.nodes.*;
	import away3d.core.managers.*;
	import away3d.materials.passes.*;
	
	/**
	 * 动画数据集类接口, 用于持有动画数据以便动画控制器类使用
	 * Provides an interface for data set classes that hold animation data for use in animator classes.
	 *
	 * @see away3d.animators.IAnimator
	 */
	public interface IAnimationSet
	{
		/**
		 * 通过给定的名称检测是否有对应的动画节点对象被注册至动画集
		 * Check to determine whether a state is registered in the animation set under the given name.
		 *
		 * @param name 需要检查的动画节点对象的名称. The name of the animation state object to be checked.
		 */
		function hasAnimation(name:String):Boolean;
		
		/**
		 * 通过给定的名称从动画数据集取得对应的动画节点对象
		 * Retrieves the animation state object registered in the animation data set under the given name.
		 *
		 * @param name 需要被取得的动画节点对象的名称. The name of the animation state object to be retrieved.
		 */
		function getAnimation(name:String):AnimationNodeBase;
		
		/**
		 * 指明与顶点寄存器组合的动画数据集包含的属性是否正在GPU着色器上渲染材质, 以允许动画数据利用GPU调用.
		 * Indicates whether the properties of the animation data contained within the set combined with
		 * the vertex registers aslready in use on shading materials allows the animation data to utilise
		 * GPU calls.
		 */
		function get usesCPU() : Boolean;
		
		/**
		 * 在测试着色器的寄存器空间是否可用于运行基于GPU的动画代码之前调用以重设GPU可用性标识    
		 * Called by the material to reset the GPU indicator before testing whether register space in the shader
		 * is available for running GPU-based animation code.
		 *
		 * @private
		 */
		function resetGPUCompatibility() : void;
		
		/**
		 * 当着色器的寄存器空间不再可用于运行基于GPU的动画代码时清除GPU的可用性标识
		 * Called by the animator to void the GPU indicator when register space in the shader
		 * is no longer available for running GPU-based animation code.
		 *
		 * @private
		 */
		function cancelGPUCompatibility() : void;
		
		/**
		 * 为动画生成AGAL顶点着色器代码, 根据材质Pass对象的需求进行定制生成.
		 * Generates the AGAL Vertex code for the animation, tailored to the material pass's requirements.
		 * 
		 * @param pass 用于生成AGAL代码的MaterialPassBase对象. The MaterialPassBase object to whose vertex code the animation's code will be prepended.
		 * @param sourceRegisters 材质Pass的属性寄存器. The animatable attribute registers of the material pass.
		 * @param targetRegisters 材质Pass的目标寄存器. The animatable target registers of the material pass.
		 * @return 让顶点数据"动"起来的AGAL顶点着色器代码. The AGAL Vertex code that animates the vertex data.
		 *
		 * @private
		 */
		function getAGALVertexCode(pass : MaterialPassBase, sourceRegisters : Vector.<String>, targetRegisters : Vector.<String>) : String;
		
		/**
		 * 根据材质Pass对象的需求定制生成动画的AGAL段着色器代码
		 * Generates the AGAL Fragment code for the animation, tailored to the material pass's requirements.
		 * 
		 * @param pass 用于生成AGAL代码的MaterialPassBase对象. The MaterialPassBase object to whose vertex code the animation's code will be prepended.
		 * @param shadedTarget 遮蔽对象.
		 * @return 对应的段着色器AGAL代码. The AGAL Vertex code that animates the vertex data.
		 *
		 * @private
		 */
		function getAGALFragmentCode(pass : MaterialPassBase, shadedTarget : String) : String;
		
		/**
		 * 当需要UV数据时生成额外的AGAL段着色器代码, 根据材质的Pass对象定制生成.
		 * Generates the extra AGAL Fragment code for the animation when UVs are required, tailored to the material pass's requirements.
		 * 
		 * @param pass 用于生成顶点着色器AGAL代码的MaterialPassBase对象. The MaterialPassBase object to whose vertex code the animation's code will be prepended.
		 * @param UVSource 代表UV源寄存器的字符串. String representing the UV source register.
		 * @param UVTarget 代表UV目标寄存器的字符串. String representing the UV target register.
		 * @return UV数据的AGAL UV代码 The AGAL UV code that animates the UV data.
		 *
		 * @private
		 */
		function getAGALUVCode(pass : MaterialPassBase, UVSource : String, UVTarget:String) : String;
		
		/**
		 * 重置顶点着色器和段着色器的AGAL代码创建的所有常量
		 * Resets any constants used in the creation of AGAL for the vertex and fragment shaders.
		 * 
		 * @param pass 当前正被用于渲染Geometry的材质Pass对象. The material pass currently being used to render the geometry.
		 *
		 * @private
		 */
		function doneAGALCode(pass:MaterialPassBase):void;
		
		/**
		 * 依据被渲染的Mesh对象设置动画需求的GPU渲染状态
		 * Sets the GPU render state required by the animation that is independent of the rendered mesh.
		 * 
		 * @param stage3DProxy 正在执行渲染的Stage3DProxy对象. The proxy currently performing the rendering.
		 * @param pass 正被用于渲染Geometry的材质Pass. The material pass currently being used to render the geometry.
		 *
		 * @private
		 */
		function activate(stage3DProxy : Stage3DProxy, pass : MaterialPassBase) : void

		/**
		 * 清除被当前动画设置过的GPU渲染状态
		 * Clears the GPU render state that has been set by the current animation.
		 * 
		 * @param stage3DProxy 正在执行渲染的Stage3DProxy对象. The proxy currently performing the rendering.
		 * @param pass 正被用于渲染Geometry的材质Pass. The material pass currently being used to render the geometry.
		 *
		 * @private
		 */
		function deactivate(stage3DProxy : Stage3DProxy, pass : MaterialPassBase) : void
	}
}
